perm filename HEMON.KKP[UP,DOC] blob
sn#002780 filedate 1972-10-06 generic text, type T, neo UTF8
HAND/EYE MONITOR 1
TABLE OF CONTENTS _________________
SECTION I. THE MESSAGE SWITCHER 1-1
A. INTRODUCTION TO MONITOR I/O 1-1
B. LINE MODE 1-1
1. MESSAGE FORMATS 1-1
2. DEFAULT OPTIONS (EXCEPT FOR TTY) 1-2
3. CHARACTER CONVERSION (EXCEPT FOR TTY) 1-2
4. TTY CHARACTER CONVERSION 1-2
5. TTY DEFAULT OPTIONS AND OUTPUT FEATURES 1-3
6. DUPLEXING HACK 1-3
C. USER VS. SYSTEM MODE 1-4
D. I/O SWITCHES 1-4
E. OPERATION OF THE MESSAGE SWITCHER 1-5
F. WORD AND CHARACTER MODE 1-6
G. TRACING 1-8
H. PROGRAM INITIALIZATION 1-8
I. DISPLAY OUTPUT 1-9
J. ERROR MESSAGES 1-9
SECTION II. THE COMMAND DECODER 2-1
A. COMMAND FORMAT 2-1
B. RECOGNIZED COMMANDS 2-2
C. ERROR MESSAGES 2-7
SECTION III. THE ERROR HANDLER 3-1
AND/EYE MONITOR 2
SECTION IV. USER SUBROUTINES 4-1
DISLNK
IFMON
MONIN
SECTION V. THE MACRO HANDLER 5-1
HAND/EYE MONITOR 3
The hand/eye monitor (referred to hereafter as the monitor)
runs as a job under the PDP-10 timesharing system (referred to
hereafter as the system) and controls subjobs created by it,
switching messages between them and executing system commands for
them.
It does this by creating pseudo-teletypes (PTYs). Output to a
PTY from the monitor is equivalent to a person typing on a TTY. In
particular, a subjob can be logged in and a program run under it.
Then, any TTY output the program does appears in the monitor's PTY
input buffer and anything the monitor outputs from its PTY output
buffer becomes TTY input to the subjob.
The monitor has three sections. The message switcher accepts
messages from subjobs and routes them to to specified subjob, (in
some parts of the program, including this one,the teletype and the
monitor are considered subjobs also). The command decoder receives
messages addressed to the monitor and executes the commands contained
in them. The error handler receives strings with no destination
specified. It determines whether or not they were produced by the
system in response to a system command put in the source subjob's
PTY. If they were, the messages are replaced by error strings which
are more easily decoded and which are sent to the subjob issuing the
message to the monitor which caused them. If this is not clear, fear
not. Read the detailed description of each section. Hopefully, that
will prove enlightening.
HAND/EYE MONITOR 1-1
SECTION I. THE MESSAGE SWITCHER ________________________________
A. INTRODUCTION TO MONITOR I/O
The monitor's I/O is easier to use than to explain. There are
three modes of I/O: Line, Word, and Character. Only Line Mode is
used between subjobs. All three modes are used between subjobs and
the TTY. The TTY also has different character conversions in some
modes. Therefore, Line Mode will be explained first and later the
differences between it and the other modes will be revealed to you.
B. LINE MODE
B1. MESSAGE FORMATS
A message between two subjobs consists of a string of
characters, terminating with a line feed or a ↑Z. Its maximum length
is 104 characters. If a subjob sends a string of characters with
many line feeds in it, the characters up to each line feed are
considered a seperate message by the monitor. If two subjobs send a
multi-line string to the same subjob, the messages may be intermixed
by the monitor, but an individual message will always be sent intact.
The source subjob, which originates the message, must indicate
the destination by prefixing to the message the logical name of the
destination subjob, with a semicolon between the name and the
message. A subjob's logical name is a string of five or fewer
letters and digits. The logical name is associated with the subjob
by the LOGIN and ATTACH commands, when executed through the monitor
(see Section II). Therefore, if subjob HAND wants to send a
message,MESSAGE, to subjob EYE, it would output through it's TTY
EYE;MESSAGE
The message would appear in the PTY input buffer associated
with subjob HAND in the monitor. The destination would be stripped
off and the message put in the PTY output buffer associated with
subjob EYE. In order that EYE will know where the message came from,
the source name is prefixed, followed by a semicolon, and the string
HAND;MESSAGE
appears in EYE's TTY input buffer.
There are three special logical names. They are:
TTY The teletype is specified as source or destination.
HAND/EYE MONITOR 1-2
null If no name precedes the semicolon, the message is to be
sent to, or is comming from, the monitor itsself.
%ALL This specifies that the message is to go to all subjobs
enabled to receive this type of message (see Part D below).
It will never appear as a source name.
B2. DEFAULT OPTIONS (EXCEPT FOR TTY)
If no destination is specified for a message, it will be sent
to the TTY. This causes the right thing to happen for system error
messages, such as IGL MEM REF, and output from programs which do not
know about the monitor, such as SAIL, STOPGAP, etc.
B3. CHARACTER CONVERSION (EXCEPT FOR TTY)
The monitor tries, as much as possible, to transmit all
characters received by it to their destination with no changes. All
buffering in the monitor is done with nine bit bytes so characters
with control bits, such as from the III keyboards, will reach their
destination with the control bits still there. If the destination is
the TTY, of course, they will be lost through no fault of the
monitor. The only characters which will not get through the monitor
- between subjobs, not the TTY - are:
↑Z terminates a message but is not transmitted to the
destination subjob (line feed is transmitted).
↑A is eaten by the monitor for reasons which will not be
mentioned here.
B4. TTY CHARACTER CONVERSION
In addition to the characters mentioned in B3, the TTY input
routine intercepts the following other characters:
↑C, ↑O, ↑P, ↑F, ↑B, ↑Q, ↑S
and their III equivalents are intecepted by the system.
↑U and its III equivalent goes to the monitor since the
monitor does input in character mode (this is the system's
character mode, not to be confused with the monitor's). It
deletes the entire line typed so far. A carriage return
and line feed are echoed.
HAND/EYE MONITOR 1-3
rubout goes to the monitor also. The monitor deletes one
character for each rubout typed and echoes the character
deleted ($ is echoed for alt mode). A double backslash is
typed before the first echoed character. When the next
character other than rubout is typed, another pair of
backslashes is typed, preceded and followed by the last
character you typed. If the buffer is empty, the rubout
acts like ↑U.
B5. TTY DEFAULT OPTIONS AND OUTPUT FEATURES
The default destination for the TTY is originally the monitor.
Therefore, when the monitor is started, you are talking to the
monitor itsself until you specify a different destination. Unlike
the subjobs, the TTY can change its default destination. A logical
name specified either on input or output changes both the default
source and destination. Thus, if a subjob sends a message requesting
input, the next line typed in will go to that subjob if no
destination is specified. Be sure to note, however, if you wish to
send a message which has a semicolon in the first six characters, the
destination must be prefixed or the first part of the message will be
taken as a destination name.
Whenever the monitor is ready to accept input from the TTY, in
Line Mode, it types out a "+". Preceding the plus is the logical
name of the default destination. If nothing precedes the plus, you
are talking to the monitor. For example: (see Section II for meaning
of the messages if you cannot quess)
.R MONITR load monitor
HAND/EYE MONITOR VERSION 1-A.0 monitor is initialized
+A$L 1,KKP login subjob A
A 10 LOGGED IN message from monitor
+RUN DSK FOO run a program
A;A+ <cr><lf> from FOO. Now you will
be talking to A
A+TYPE COMMAND message from FOO
A+CAL message to FOO from TTY
A+;K message from TTY to monitor
;A 10 KILLED message from monitor
B6. DUPLEXING HACK
The PTY's are used with duplexing turned off. Unfortunately,
there is no way to prevent the echoing of $ for alt modes.
Therefore, whenever an alt mode is sent to a PTY, the next $ coming
back will be eaten. If a subjob sends a $ in a message when an alt
HAND/EYE MONITOR 1-4
mode is being sent to it and the wrong $ is eaten, complain to Poole.
C. USER VS. SYSTEM MODE
The mode of the subjob's TTY (or PTY, depending on which end
you are at) determines how messages are sent to it. A message can be
sent to a subjob only when it is in user mode, so that the message
goes to a program. If the subjob is in system mode, messages put
into it's TTY buffer will go to the system's command interpreter. To
enable the monitor to keep track of the status of subjobs, a subjob
cannot send a message to another subjob when the latter is in system
mode. Otherwise, subjobs could login, kill, or otherwise change the
subjob without the monitor knowing about it. Therefore, when a
subjob is in system mode, messages to it, which are really system
commands, must be sent as messages to the monitor, whose command
decoder will process them. Monitor messages are discussed in Section
II.
D. I/O SWITCHES
Subjobs may set switches to exercise control over various I/O
options. The subjobs, including the TTY, may set the switches for
themselves or other subjobs. If you set switches for another subjob
in a way it was not expecting, you will get what you deserve. The
switches may be changed or interrogated by means of the STATUS
command to the monitor (see Section II). The switches are referred
to by letters and are given below in pairs. One member of each of
the four pairs negates the other member. Below, and in the rest of
the manual, when I say a switch is assumed set, that means that the
switch is not changed but the monitor acts as though it were set. If
I say that a switch is forced set, the switch is changed by the
monitor to insure it is really set.
Switch Action________________
E Subjob is enabled to receive messages addressed to it.
D Subjob is disabled and will not accept any messages, except
from the TTY or the monitor`s command decoder. If this
switch is set, switch S is assumed on.
S Suppress source name. Messages received by this subjob
will never have a source name prefixed. This switch is
necessary for FORTRAN programs ,which have trouble scanning
strings with the source prefixed.
P Prefix source names unless switch D is set.
F Force messages to disabled subjobs (switch D set) to appear
HAND/EYE MONITOR 1-5
on the TTY.
T Messages to disabled subjobs will be eaten by the monitor.
M This subjob will accept %ALL messages.
N This subjob will not accept %ALL messages.
To further explain switches F and T, suppose subjob A sends a
message to subjob B. If B is in system mode, or in user mode with
switch D set, and A has switch F set, the message will not go to B,
but will be sent to the TTY as
(B)A;MESSAGE
where the parens enclose the name of the original destination. If A
has switch T set, the message will be eaten by the monitor. In
either case, A is not informed that B did not receive the message.
The monitor has switches E, S, F, and N set initially. E and
S are protected but all others can be changed. The TTY has switches
E, P, F, and N set; E is protected.
E. OPERATION OF THE MESSAGE SWITCHER
Here we have a brief pause to give you a quick, and almost
honest, peek at the inner workings of the message switcher, greatly
simplified.
The monitor scans the PTY's, the TTY, and the monitor checking
for input. For each device, it calls an input waiting test routine
which gets any characters from that device which are waiting and puts
them in a buffer. Whenever the input routine decides that a string
is ready, depending on the mode of that device (i.e. in Line Mode it
has just seen a line feed or ↑Z), it gives the contents of the buffer
to the message switcher; otherwise, the monitor continues scanning.
When input is received, the destination is determined and the message
is transmitted to the proper output routine; then scanning continues.
Thus, after a message is received from a subjob, all other subjobs
are checked for input before it is checked again. This prevents one
subjob from monopolizing the message switcher with a continuous
stream of messages to the exclusion of other subjobs.
If the message is for the monitor, the output routine jumps to
the command decoder, described in Section II. If the command decoder
has output it returns to the message switcher, pointing it at the
proper destination; otherwise, it jumps back to the scanning loop.
If the command decoder has more than one line of output, it sets a
flag for its input waiting test routine. The next time that input
HAND/EYE MONITOR 1-6
routine is called by the scanner, it calls another entry to the
command decoder, which is partially reentrant, to output the next
line.
If the message is for the TTY, its output routine outputs the
message only if the TTY is not in the middle of typing a line in. If
the TTY is busy, the output is put in a linked list of TTY buffers.
Once during each scan of the inputs, the list is checked and, if not
empty and the TTY is now free, the oldest message will be typed.
This keeps output from interrupting your input in the middle of the
line (the system should be so nice !!). Also, if a lot of output is
appearing, like from the SYS system command, typing in any character
will stop the output so you can admire it.
In particular, as mentioned in Section II, the command decoder
ignores messages consisting only of blanks. Therefore, if you are
talking to the monitor, typing a blank will stop output until a
carriage return is typed, with no complaints from the command decoder
about illegal commands. If you are talking to a subjob, type
<carriage return>;<space> to stop output.
If you fill all the TTY output buffers, the bell is run if you
are on a teletype or the word "HUNG" appears in big letters at the
bottom of the screen if you are on a display. Until some buffers are
released all message switching is turned off.
F. WORD AND CHARACTER MODES
While Line Mode is fast and fairly efficient, many system
programs won't work in this mode. RAID, DDT, and STOPGAP expect
input strings of less than a full line. Other system programs type
askterisks at the beginning of each line. In Line Mode they would
not appear until the next line was typed out.
Word and Character Mode are used together. The user or a
program can put any subjob into Word Mode by a monitor command.
Also, whenever a program is started it is automatically put into Word
Mode (see Section II for the commands that do this). The program can
put itsself into Line Mode with a monitor command, or by enabling
itsself for messages, which automatically puts it into Line Mode.
Note, however, that disabling messages doesn't put it back into Word
Mode. Any subjob put into Word Mode has switch D forced on. If any
subjob is in Word Mode, the TTY is put in Word Mode when talking to
that subjob.
In Word Mode a string is switched whenever a character is seen
HAND/EYE MONITOR 1-7
which is not a letter or a digit. This allows DDT, for example, to
type out without a line feed ending the string.
Character Mode is turned on and off automatically. When a
subjob is in Word Mode, the TTY has that subjob as its default
destination, and the last string from the TTY terminated with
something other than a line feed or a period from the system, the TTY
and the subjob go into Character Mode. Simply, this means that
whenever any subjob is in Word Mode, the TTY goes into Word Mode just
long enough to get the first string at the start of a line to
determine which subjob it is talking to. If it was talking to a
subjob in Word Mode, and the string does not end with a semicolon, or
it does end in a semicolon and the destination specified is in Word
Mode, both the TTY and the subjob go into Character Mode; otherwise,
the subjob stays in Word Mode and the TTY goes into Line Mode.
In Character Mode the characters are switched between the TTY
and the subjob one by one as they are received. No destinations may
be specified in this mode. Whenever a line feed is typed on the TTY,
the TTY and the subjob will go back into Word Mode. Then, the TTY
may specify another destination or the subjob can enable itsself for
messages from other subjobs; either action will break the link.
The effect of these mode is whenever the TTY starts talking to
a subjob in Word Mode characters are sent back and forth as they come
in, with TTY input and output from the subjob mixed on the line.
Neither can talk to any other subjob, nor can any other subjob type
on the TTY. The only way to break the link between the TTY and the
subjob is to type a carriage return or line feed and then type a new
destination.
These modes have one mildly obnoxious feature. Then talking
to STOPGAP in alter mode, control characters will be duplexed as well
as text characters Also, if a symbol, followed by a semicolon, is
typed to RAID at the start of a line to open a cell, the symbol will
be taken as a destination name by the monitor. There are two fixes
for this feature. You can always start the line with a destination,
even though the default name is correct. Then the semicolon will be
the first seperation characters. Also, you can start the line by
typing <ctrl 2, ctrl1>LF on the III keyboards or either ↑A or ↑Z on
the teletypes. All three are considered to be seperation characters
and will put you in Character Mode but they are eaten by the monitor
as explained above so the program you are running will never see
them. ↑U and rubout will be sent from the TTY to the subjob instead
of deleting characters. Also, typing spaces in Character Mode to
stop TTY output works very poorly due to sychronization problems.
For best result, precede the spaces with carriage return and
semicolon.
HAND/EYE MONITOR 1-8
This mode is recommended only for running system programs when
there are no subjobs switching messages since the efficiency of the
monitor is greatly impared. Consider, for example, that in Character
Mode talking to STOPGAP in alter mode, each character you type is
rebuffered 14 times before it is typed back at you. If it comes back
with frayed bits, be glad you got any of it back.
G. TRACING
To help debug interaction between subjobs, tracing of messages
can be turned on and off for any or all subjobs by monitor commands.
All messages to or from a subjob which has tracing on will be sent to
the trace output device in the form
A;B;MESSAGE
where A is the source and B is the destination. If B is disabled and
A has switch F set, the trace output is
(B)A;TTY;MESSAGE
but if A has switch T set the only output is the trace output,
consisting of
(B)A;###;MESSAGE
Character Mode I/O will never be traced. Messages with the
destination %TRA will be traced if tracing is on but will not be sent
to any other subjob. This allows programs to put debugging
information in the trace file. The destination for these messages is
%TRA.
H. PROGRAM INITIALIZATION
Starting the monitor kills all subjobs, resets the default
sources and destinations to their initial values, clears all status
switches, and reclaims all TTY buffers for its free storage list.
The trace device is closed and tracing is turned off. Word mode is
turned on for all devices. Note that resetting the I/O, either by
the user or the system , kills all subjobs. The reenter address
initializes the pushdown list, clears I/O in progress, and continues
scanning. It releases no devices and does not affect the operation
of the subjobs, unless they were in the middle of sending a message.
I. DISPLAY OUTPUT
Any subjob may display if the monitor is running on a display.
HAND/EYE MONITOR 1-9
As this feature is currently implemented, all subjobs share the same
display buffer in the system and, therefore, the sum of the lengths
of the used portions of their individual display buffers must be less
than the size of one system buffer. Also, the subjobs must
coordinate their displays or they may be displaying on top of each
other. As far as the subjob is concerned, it is displaying as though
it were running directly under the system.
J. ERROR MESSAGES
The monitor has two kinds of error messages. Errors relating
to mistakes in the messages are returned to the source subjob. The
source indicated in the error message will be the monitor. These
messages are five characters long, followed, of course, by a carriage
return and line feed. The messages of this type generated by the
message switcher are:
Error Cause______________
?DST? Specified destination subjob is not logged in.
Errors relating to I/O and monitor errors are always sent to
the TTY. The message is followed by the name of the subjob causing
the error. The name of the subjob which will be returned as the
source for the error message is the subjob which was the source for
the message being processed when the error occured. The subjob
following the message, which is given below under "Subjob", is
sometimes given relative to the last message when that message caused
the error. For example, if A sends a message to B and B's input
buffer overflowed, the error message appearing on the TTY would be
A;INPUT BUFFER FULL - B
. THe messages are:
Error Subjob Cause__________________________________________
INPUT BUFFER FULL Destination Subjob's TTY input buffer is
full and will accept no more
messages.
INPUT BUFFER OVERFLOW Source Buffer for monitor messages is
full. Remember, the system TTY
buffer is shorter than other TTY
buffers.
HAND/EYE MONITOR 1-10
INIT ERROR %TRA% Initialization error for trace
device.
LINE TOO LONG Source TTY or PTY overflowed its
buffer.
ENTER ERROR %TRA% Enter error for trace device.
OUTPUT ERROR %TRA% Output error for trace device.
After each error message, the monitor is reentered. The
message being processed is lost. Special names used with these
messages are:
%MON% Monitor
%TRA% Trace device
%DUM% Dummy subjob (see next section)
HAND/EYE MONITOR 2-1
SECTION II. THE COMMAND DECODER ________________________________
A. COMMAND FORMATS
Messages between subjobs go to the user programs. Messages to
the monitor generally consist of system commands to be executed for
some subjob. These are placed in the subjob's TTY buffer after
taking the subjob out of user mode. A few commands are executed
directly by the monitor. There are four formats for monitor
messages. The examples below are the part of the entire message
referred to in the last section as "MES". The entire message wil
include a null job name, followed by a semicolon and the command.
The formats are:
A: NAME$COMMAND or COMMAND
where NAME is the logical name of the subjob to which the
command is to be applied (i. e., FOO$START will start the
program loaded for subjob FOO). If no name and $ are given,
the last NAME given in a monitor message from this subjob will
be used as a default name. The logical name %SELF will cause
the command to be applied to the source subjob. Note that the
command decode considers $ and alt mode to be identical.
Therefore, you can type alt mode at it and your programs can
send $ to it.
B: $COMMAND
The command is to be applied to the monitor. This is a special
case of format A which is treated separately since, unless it
is specified in the command description below, the command
cannot be applied to the monitor. The default name is not
changed.
C: $$COMMAND
The command applies to all subjobs logged in, including the
monitor in some cases. The command is executed at the rate of
one subjob per complete scan loop of the message switcher. A
logical name is not needed and will be ignored. The default
name is not changed.
D: COMMAND
Certain commands do not apply to a given subjob but request
information. These commands are sent to a dummy subjob using a
HAND/EYE MONITOR 2-2
reserved PTY regardless of format. Output will have the source
name of %DUM, which is suppress from appearing on the TTY
(format D commands can only be given from the TTY). The
logical name, if any, becomes the default name but is ignored
otherwise.
B. RECOGNIZED COMMANDS
Below is a list of all system commands and some information
about their function under the monitor. The letters in the column
labeled "FORMAT" are the legal formats for the command. The column
labeled "PROC" gives processing information about the command as
follows:
H The subjob will be halted before the command is put in its PTY
buffer if it is in user mode.
S The subjob will be continued after putting the command in it
PTY buffer if stopped by H.
M Format C applies to the monitor also, Otherwise it does not.
T This command is only legal from the TTY.
I Sets initial status. After the command is executed, the subjob
will have the following status, word mode on, messages
disabled, %ALL disabled, errors forced to the TTY, and source
names supressed.
Unless noted with the commands, the command structure is
identical to that used when talking to the system directly. Commands
may be abbreviated just as when giving them directly to the system,
except that the monitor's scanner only checks the first six
characters. If the command is misspelled after the sixth character,
the monitor will not detect the error, but the system will. None of
these commands can be applied to the TTY. Unless specified below,
the commands return nothing to the source subjob except, possibly,
error messages.
COMMAND FORMAT PROC COMMENTS___________________________________
none If nothing but spaces and/or alt modes
appear in the message, it is ignored.
All RPG
commands A HI Include: ADVANCE, BACKSPACE, COMPILE,
CREATE, CREF DEBUG, DELETE, DIRECTORY,
DUMP, EDIT, EXECUTE, IDUMP, LIST, LOAD,
MAKE, RENAME, RESTORE, REWIND, TECO,
HAND/EYE MONITOR 2-3
TLIST, TRY, TYPE, ZERO
ASSIGN A HS
ATTACH A A new PTY will be created and the subjob
attached. NAME must not be currently
logged in under the monitor. If
successful, a message of the form
F <logical name><job number> LOGGED IN
will be typed on the TTY.
CCONTINUE A H
CONTINUE A H
CORE A HST Outputs info to TTY.
COREX D T
CSTART A HI
DAYTIME D T Outputs to TTY.
DDT AB HI B format transfers to the monitor's
version of RAID or DDT, if loaded.
Subjobs continue running but cannot send
messages. Executing POPJ 17, returns to
the monitor. This is mainly for debugging
the monitor.
DEASSIGN A HS
DE (POSIT) A HCT
DETACH AC H The subjob is detached from the PTY,
usually for debugging it on a seperate
console. A message of the form
<logical name> <job number> DETACHED
<proj-prog number>
is typed on the TTY. After the command
has been successfully executed, the subjob
is removed from the monitor's tables and
killed. Format C detaches all subjobs.
This command stops message switching
during the first part of its operation.
E (XAMINE) A HCT
HAND/EYE MONITOR 2-4
FINISH A HS
GET A H
HALT AC Sends ↑C↑C to subjob. Format C halts all
subjobs.
HELLO illegal
HELP illegal
KJOB AC The subjob is deleted from the monitor's
tables and a message of the form
<logical name> <job number> KILLED
is typed on the TTY. Format C kills all
subjobs.
LOGIN A A new PTY will be created and the subjob
logged in. NAME must not be currently
logged in. The command is of the form
FOO$LOGIN 1,KKP
The proj.-prog. pair must be present on
the same line. If a password is needed,
the string "PWD" will be sent to the
source subjob. Wrong PPNs or passwords
cause error strings to be sent to the
source subjob (see Section III). Until
the login is completed the message
switcher will send messages to the subjob
even though it is not in user mode so the
source subjob can complete the login, if
necessary. If a command to the monitor,
other than ENABLE, refers to a subjob that
is partially logged in, the latter will be
killed. When login is successfully
completed, the message
<logical name> <job number> LOGGED IN
will be typed. This command may stop
message switching for a few seconds during
the first part of its operation.
PJOB ABC The information is sent to the source
subjob from the monitor's tables. In
format C, the subjob's name is prefixed to
each number.
PPPN AC The information is sent to the source
subjob from the monitor's tables. The PPN
will be enclosed in square brackets is the
HAND/EYE MONITOR 2-5
subjob was attached instead of logged in.
In format C, the subjob's name is prefixed
to each PPN.
REASSIGN A HI If the job reference in the command is a
logical name, the number will be
substituted if found.
REENTER AB HI See Section I-F for effect on monitor.
RUN A HI
SAVE A H
START AB HI See section I-F for effect on monitor.
TALK illegal
TIME A T Uses dummy subjob but needs a subjob name.
Outputs to TTY.
The following commands are executed by the monitor itself.
The comments before the last list of commands apply except that all
output is returned to the source subjob. Also, these commands cannot
be abbreviated.
WORDON AC Turn on word mode.
LINEON AC Turn on line mode. (Turn off word mode)
TRACE DEV ABC M Turn on tracing. The first time a device
name must be included. The output will be
on TRACE.MON on the specified device.
Subsequent calls will add subjobs to the
tracing. If a different device is
specified, the previous file will be
closed and a new one opened; otherwise the
device is ignored. This command can be
applied to the TTY.
UNTRAC ABC M Turns off tracing for the specified
subjob. When the last trace is turned
off, the trace device is released.
LJOB NUM This command requires a job number
following it. Any logical name before it
is ignored. If job NUM is logged in under
the monitor, the logical name is returned;
HAND/EYE MONITOR 2-6
a carriage return is returned otherwise.
ENABLE A This command returns one letter to the
source subjob specifying the current run
status of the specified subjob as follows:
error
message not logged in
N partially logged in
L logged in but not running
R running but not enabled for messages
E running and enabled
STATUS AB If the command is followed by a string of
letters, they are decoded and used to set
the status of the specified subjob as
follows:
D, E disable or enable for messages
N. M disable or enable %ALL messages
F, T turn on or off forcing messages
to TTY
S, P supress or pass source names
The letters may be supplied in any order,
but, if both letters of a pair are
present, the right most one will take
effect. If no letter string is present,
the monitor returns the current status as
a string of four letters, in the order the
pairs are given above.
CONTRL ARG AC ARG is a string of letters which may
include the letters A through I and N
through Z. For each letter, L, in the
string, the monitor puts ↑L in the
specified subjob's TTY input buffer. ↑C
is converted to the HALT command. This
command is for sending characters
intercepted by the system, such as ↑B, ↑O,
↑Z, etc., to subjobs. Unlike other
commands, this one does not take the
subjob out of user mode, if it is running.
HAND/EYE MONITOR 2-7
STATD DEV D T DEV is an output device, the TTY if none
is given. This command puts about 15
lines of assorted letters and digits on
file STATUS.MON on the specified device.
The output will probably not mean much to
you, but it tells me the status of the
monitor. Use it if the monitor does
something to you that you don't like and
give me the output with your complaint.
Also see Section VI.
C. ERROR MESSAGES
Sent to source subjob:
?COM? Illegal, unknown, or ambiguous command sent to
monitor. Also, a command from or to an illegal
subjob (i.e., TTY or monitor).
?JOB? Logical name not logged in and should be, or
vica versa.
?FOR? Illegal format for this command.
?ARG? LOGIN or TRACE is missing an argument, or
CONTRL has an illegal argument.
HAND/EYE MONITOR 2-8
Sent to TTY:
DETACH HUNG DETACH command told system to detach a subjob
but the system did not do so.
NO FREE PTY'S Monitor tried to init a PTY for LOGIN, ATTACH,
or a command using the dummy subjob and failed.
MESSAGE OVERLAP TTY sent the monitor a format C command before
it finished the last one.
SYS HUNG LOGIN or HALT hung waiting for a reply from the
system. Try again until it works.
other If the LOGIN command returns anything except
the job number, it is sent to the TTY.
In Section I it was stated that all messages to and from the
subjobs being traced will appear in the trace output. This is not
completely true. The following output from the monitor will never be
traced:
1. All error messages sent only to the TTY.
2. ↑C from the monitor to halt subjobs.
3. The first part of the login output.
4. The detach command.
If the error handler (see Section III) recognizes a string
given to it and either flushes it ,or replaces it with another
string, the original string will be traced. The destination will be
given as the error handler (%EAT).
HAND/EYE MONITOR 3-1
SECTION III. THE ERROR HANDER ______________________________
After putting a system command in a subjob's TTY buffer, the
command decoder returns control to the message switcher. If the
source of the command was not the TTY, the command decoder will have
stored the number of the source subjob and lists of the possible
responses of the system. Any response goes to the message switcher
as a message with no destination specified. The error handler
receives all messages with no destination and, if message lists have
been stored, compares them with the new message. As long as the
sequence of messages are the same as one of the lists, the messages
are eaten. Thus, ↑C's, line feeds, etc. will not be returned to the
subjob which sent the command to the monitor, unless it was the TTY.
If the message is the same as one of the stored responses which is
flagged as an error condition, an error string is sent to the subjob
which was stored. As soon as the messages and the lists differ,
comparing stops and the messages appear on the TTY. For example, if
subjob FOO sent the message
;ABC$RUN DSK EYE
, and subjob ABC returned the message
<cr><lf>EYE NOT FOUND<cr><lf>↑C<cr><lf>.
, the the error handler would eat the entire string and send to
subjob FOO the message
ABC;?Q?
as indicated below. The recognized messages are:
MESSAGE STRING CAN BE GENERATED BY_______________________________________________________________
TOO FEW ARGUMENTS ?A? F ATT A REA GET RUN SAVE
ALREADY ASSIGN TO JOB n ?B? A
LOGICAL NAME ALREADY IN USE ?C? A
NO SUCH DEVICE ?D? A REA GET RUN SAVE
ILLEGAL JOB NUMBER ?E? ATT REA
PROJECT-PROGRAMMER
NUMBER MISMATCH ?F? ATT
HAND/EYE MONITOR 3-2
ALREADY ATTACHED ?G? ATT
JOB NEVER WAS INITIATED ?H? ATT REA
CAN'T CONTINUE * ?I? CCONT CONT S CSTART
NO CORE ASSIGNED ?J? CCONT CONT S CSTART DDT
REE
NO STARTUP ADDRESS ?K? S CSTART
NO DDT ?L? DDT
xxx WASN'T ASSIGNED ?M? DEA
Finish what ??? ?O? F
DEVICE xxx NOT AVAILABLE ?P? RUN GET SAVE
xxx NOT FOUND ?Q? RUN GET
WASN'T ASSIGNED ?R? REA
xxx CAN'T BE REASSIGNED ?S? REA
NO REENTER ADDRESS ?T? REE
?SORRY --- WRONG NUMBER ** ?V? LOGIN
PASSWORD = ** PWD LOGIN
?INCORRECT CODE --- TRY AGAIN ** ?Y? LOGIN
* Can also occur with any command which causes the monitor to stop
and continue the program running for the subjob if another error
occurs.
** Source subjob can send messages to the subjob being logged in to
complete the login. Also, the error string will even appear on
the TTY. Sorry about that
HAND/EYE MONITOR 4-1
SECTION IV. USER SUBROUTINES _____________________________
The following subroutines are available for programs using the
monitor. They may be found on the hand/eye library file,
HELIB.REL[1,3].
DISLNK ______
EXTERNAL BOOLEAN PROCEDURE DISLNK;
This procedure tells the system to put the program's display
output on the monitor's display, if the program is running as a
subjob under the monitor (i.e. running on a PTY). It does a normal
dpyclr if it is running on a display. It is TRUE if the program is
running on a PTY or a display. It is FALSE is the program is on a
teletype. NOTE: This procedure has no way of knowing whether the
monitor is on a teletype or a display.
IFMON _____
EXTERNAL BOOLEAN PROCEDURE IFMON;
This procedure is TRUE if you are running as a subjob under
the monitor and FALSE otherwise.
MONIN _____
This is a subroutine to be called from assembly language
programs only. The SAIL version is trivial; the FORTRAN version is
impossible. Its calling sequence is
PUSH 17,[SOURC]
PUSH 17,[POINTR]
PUSHJ 17,MONIN
MONIN will input one message, terminating in a <line feed>
followed by a zero byte. If a source name is prefixed (i.e. a ";"
is seen as one of the first six characters), the name is put in SOURC
in ASCII; otherwise SOURC will not be changed and will continue to
HAND/EYE MONITOR 4-2
contain the last source found, which, by default, is the current
source. SOURC should be initialized by the user to zero or "TTY",
depending on the initial conditions desired. A byte pointer to the
first character of the message, with the source name, if any,
removed, is put in POINTR. All input is done with TTY UUO's. No
files are opened.
HAND/EYE MONITOR 5-1
SECTION V. THE MACRO HANDLER _____________________________
Sequences of TTY input strings, called macros, can be given
names and executed by refering to the name. Macros can be stored in
core or on the disk. If you refer to a macro which is not in core,
most commands will load it automatically from the disk.
While in core, macros reside in the buffers used for TTY I/O.
The I/O routines always leave at least forty buffers for macros
(there are currently 140 buffers). All macros read in from the disk
or written out are marked that they are on the disk. Whenever a
macro is refered to in a command it is marked that is was accessed.
Whenever the supply of buffers is exhausted, the macros which are
marked that they are on the disk are deleted from core, as necessary,
starting with the one not accessed for the longest time. When there
are none already on the disk, macros are written out and deleted,
again starting with the oldest access. Macros begin defined or
executed will never be written out until the process is completed.
On the disk macro NAME will be stored in file NAME.MCR in STOPGAP
format. Macros may be created by using STOPGAP.
The following commands are implemented. All are legal only
from the TTY and, unless stated otherwise, all are format D commands
are are legal inside and outside of a macro definition.
MACRO NAME
starts a macro to be called NAME. All TTY input following
this command becomes part of the macro. It is illegal if you are
already inside a macro definition. If a macro already exists in core
with this name, it is an error. The disk is not checked. The macro
will be executed while you enter it. Any error in execution or
message switching, or starting the monitor over will terminate the
macro.
END
Terminates the macro definition currently in progress; it is a
no-op outside of a macro definition. The name of the macro
terminated will be typed out. Note that this command is executed
automatically by the monitor initialization routine and the error
routines.
PRINT NAME
prints the definition of macro NAME, reading it in from the
disk if necessary. If no name is given, the names of the macros
currently in core will be listed.
HAND/EYE MONITOR 5-2
MACKIL NAME
will delete macro NAME from core, but not the disk (try the
DELETE command for that). It is not legal inside a macro.
MACOUT NAME
writes out macro NAME onto the disk. If no name is given, all
macros are written out. The macros are marked that they are on the
disk but they are not deleted from core. It is a no-op if the macro
does not exist in core.
DO NAME
executes macro NAME, reading it in from the disk if necessary.
If executed while inside a macro, the first one will be stacked and
continued when the inner macro(s) is finished. Macros may be nested
to a depth of 20. While executing a macro, TTY input is ignored as
the macro strings are substituted for it. The monitor will exit from
this state when (1) the macro terminates, (2) an error message is
sent to the TTY from the monitor, or (3) the monitor is reentered.
NOTYPE
suppresses all (repeat all) TTY output during the remainder of
the current macro; it is a no-op otherwise.
MTYPE
turns typing on after a NOTYPE command. This is the default
state. In this state, all output will appear on the TTY as though
the strings in the macro definition were being typed in. The macro
strings, however, will only appear in traces.
WAIT
is a format A or B command. Inside a macro it causes the
macro to wait until a string is sent to the TTY (even if NOTYPE has
been executed) from the specified subjob. Note that the output must
occur after the WAIT command is executed. This synchronizes subjob
I/O with the macro.
The following command described in Section II operates
differently inside a macro:
ENABLE N
If N is present and you are inside a macro, the macro will
HAND/EYE MONITOR 5-3
delay until the output of the command would be N, where N is ?JOB?,
N, L, R, or E. This synchronizes subjob status with the macro.
Thus, the sequence
EYE$L H,HE
ENABLE L
inside a macro will not continue until the login is finished.
If N is not present or you are not inside a macro, the command
works as described earlier.
The following error messages can occur while using macros:
ALREADY EXISTS A MACRO command has refered to a macro
which already exists in core.
DOES NOT EXIST A command has refered to a macro which
does not exist.
NO NAME FOR MACRO A command which requires a macro name
does not have one.
NOT LEGAL IN MACRO A command has been given inside a macro
which is not legal there.
DISK INIT ERROR-MACINT Could not initialize the disk to read a
macro.
INIT ERROR-MOUTX Could not initialize the disk to write
out a macro.
ENTER ERROR-MONIN the ENTER operation failed when writing
out a macro.
INPUT ERROR-MONIN Disk input error when reading a macro.
OUTPUT ERROR-MOUTX Disk output error when writing out a
macro.
LINE TOO LONG A macro line is over 127(octal)
characters long on input from the disk.
NO FREE BUFFERS The macro handler is out of free
buffers.